본문으로 건너뛰기

7.4.3 사용자의 온체인 주소 획득

#간단한 설명: 사용자의 온체인 주소를 가져옵니다(존재하지 않는 경우 생성).

쿼리 매개변수​

매개변수 이름유형필수매개변수 의미매개변수 설명
merchantIdint64예판매자 ID
userIdstring예사용자 ID판매자 로컬 사용자 고유 ID
networkstring예메인넷TRON, BSC, POLYGON, ETHEREUM 지원(문서 7.4.2를 통해 사용 가능)
keystring예판매자 키플랫폼 할당 판매자 키
signstring예서명 참조(서명 방법)자세한 내용은 규칙에 서명하는 방법을 참조하세요
json 샘플 요청​
{
  "merchantId": "302992856974",
  "userId": "77",
  "network": "TRON",
  "key": "9yUreYgTRtit39Dy",
  "sign": "3876e3b40ce4938c3123f07cd5aecb8c"
}

응답 JSON 예시

{
  "code": 0,
  "data": {
    "address": "TMWFqTEZMDRxNzyfudFBw4rn7QFvMt4kSN",
    "merchantId": 308116064181,
    "network": {
      "avgBlockSecond": 3,
      "coinTotal": 2,
      "collectionNetworkConfirm": 3,
      "displayName": "Tron",
      "estimatedMinute": 1,
      "isDefault": null,
      "level": null,
      "logo": "https://dx-public-download.s3.ap-southeast-1.amazonaws.com/blockchain-logo/tron.png",
      "masterCoin": "TRX",
      "name": "TRON",
      "networkType": "TRON",
      "queryBaseUrl": "https://nile.tronscan.org/",
      "withdrawalNetworkConfirm": 3
    },
    "userId": "33"
  },
  "success": true,
  "message": null
}
응답 데이터 매개변수 설명​
매개변수 이름유형매개변수 의미비고
merchantIdint64판매자 ID
userIdstring사용자 ID판매자의 로컬 사용자 고유 ID
addressstring체인 주소사용자의 체인 주소
networkobject체인 메인 네트워크 정보
└ 이름string메인넷 이름
└ queryBaseUrlstring온체인 쿼리 URL
└ collectionNetwork확인int64충전망 확인 건수
└출금네트워크확인int64출금 네트워크 확인 건수
└ 코인토탈int64동전의 수
└ 마스터코인string메인체인 화폐
└ 네트워크 유형string기본 네트워크 유형(클라이언트가 주소 유형을 저장하려는 경우 이 필드를 사용하십시오)
└ 마스터코인string메인체인 화폐
└ 평균블록초num평균 블록 시간(초)
└ 추정분num입금 예상시간(분)
└ 디스플레이이름string메인넷 표시 이름
└ 로고string로고 주소

콜백 알림

사용자 주소가 결제를 받고 주문이 처리되면 시스템은 판매자가 구성한 기본 콜백 주소로 알림 메시지를 보냅니다.

콜백 주소 구성​

이 인터페이스는 요청 매개변수를 통한 notifyUrl 지정을 지원하지 않습니다. 시스템은 판매자의 백엔드에서 구성한 기본 콜백 주소를 콜백합니다. 기본 콜백 주소는 가맹점 생성 시 제공되며, 운영관리 백그라운드에서 유지될 수 있습니다.

콜백 요청 방법​

HTTP 방법

POST

콘텐츠 유형

application/json

콜백 데이터 예시​

자금 출처에 따라 콜백 데이터는 다음 세 가지 상황으로 구분됩니다.

시나리오 1: 체인(다른 지갑)을 통해 이 주소로 전송​

온체인 전송 시나리오는 blockchain 온체인 거래 정보를 반환합니다.

{
  "amount": "6",
  "bizType": "PAYMENT_TRANSFER",
  "blockchain": {
    "network": "TRON",
    "receiverAddress": "TMWFqTEZMDRxNzyfudFBw4rn7QFvMt4kSN",
    "senderAddress": "TPutFhYUQnrRxHSmKVwjp55vgk9QY6r5nS",
    "txId": "8265e6b65d8aad4727b55f79880941c1e22df54278a1f78b28d760eb7328a0d2",
    "txIndex": 0
  },
  "currency": "USDT",
  "merchantActualAmount": "38.86",
  "merchantCurrency": "CNY",
  "merchantId": 308116064181,
  "merchantPaidAmount": "38.86",
  "merchantUserId": "33",
  "notifyTime": 1783671086642,
  "orderCreateTime": 1783671075931,
  "orderId": "566708436246981",
  "status": "SUCCESS",
  "type": "PAYMENT",
  "userAmount": "6",
  "userCurrency": "USDT",
  "userReceivableAmount": "6",
  "sign": "b0d2d52d8dc41af9373431fc8b2b2d6a"
}

시나리오 2: 내부 지갑을 통해 이 주소로 전송​

내부 지갑 결제 시나리오는 지급인의 walletUserId를 반환합니다.

{
  "amount": "7",
  "bizType": "PAYMENT_TRANSFER",
  "currency": "USDT",
  "merchantActualAmount": "45.33",
  "merchantCurrency": "CNY",
  "merchantId": 308116064181,
  "merchantPaidAmount": "45.33",
  "merchantUserId": "33",
  "notifyTime": 1783671928955,
  "orderCreateTime": 1783671928956,
  "orderId": "566715422826565",
  "status": "SUCCESS",
  "type": "PAYMENT",
  "userAmount": "7",
  "userCurrency": "USDT",
  "userReceivableAmount": "7",
  "walletUserId": 3,
  "sign": "08c9b45f19709f9d4e8ffbd5bc852eb9"
}

시나리오 3: Merchant OpenAPI를 통해 이 주소로 자금을 인출합니다​

Merchant OpenAPI를 통해 출금 주문이 생성되어 이 주소로 출금되면 원본 출금 주문 정보 fromWithdraw가 반환됩니다.

{
  "amount": "8",
  "bizType": "PAYMENT_TRANSFER",
  "currency": "USDT",
  "fromWithdraw": {
    "localOrderId": "17751376202610003",
    "merchantId": 308116064181,
    "orderId": 566716344475973
  },
  "merchantActualAmount": "51.81",
  "merchantCurrency": "CNY",
  "merchantId": 308116064181,
  "merchantPaidAmount": "51.81",
  "merchantUserId": "33",
  "notifyTime": 1783672041921,
  "orderCreateTime": 1783672041922,
  "orderId": "566716348211653",
  "status": "SUCCESS",
  "type": "PAYMENT",
  "userAmount": "8",
  "userCurrency": "USDT",
  "userReceivableAmount": "8",
  "walletUserId": 2,
  "sign": "fc648e11787ccd94accd139453a3c69b"
}

**비즈니스 개발 요구 사항을 충족하기 위해 콜백 매개변수는 향후 새로운 필드를 추가할 수 있습니다. 새로 추가된 필드는 기본적으로 서명 계산에 참여합니다(서명 규칙에 특별히 명시된 필드 제외). 따라서 가맹점 시스템은 필드 확장으로 인한 서명 검증 실패를 방지하기 위해 향후 호환성을 갖추어야 합니다. **

콜백 매개변수 설명​

매개변수 이름유형참여 서명매개변수 의미매개변수 설명
amountdecimal예주문금액
bizTypeenum예사업 유형PAYMENT_TRANSFER로 고정
blockchainobject예온체인 거래정보온체인 전송 및 재충전 시나리오만 반환됩니다
└ 네트워크String예메인넷
└ 수신자주소String예수신자 주소
└ 보내는 사람주소String예보내는 주소
└ TXIDString예거래 ID블록체인 거래 해시
└ tx인덱스int예거래지수
currencyString예통화 주문
fromWithdrawobject예출금주문 정보 출처OpenAPI를 통해 이 주소로 돈을 인출하는 시나리오만 반환됩니다.
└ 로컬주문IDString예소스 판매자 주문 번호
└ 판매자IDint64예출금주문 가맹점 아이디
└ 주문IDint64예소스 플랫폼 주문 번호
merchantActualAmountdecimal예가맹점 실제 결제 금액
merchantCurrencyString예가맹점 결제통화
merchantIdint64예판매자 ID
merchantPaidAmountdecimal예가맹점채권금액
merchantUserIdString예판매자 사용자 ID주소 획득 인터페이스에 해당하는 userId
notifyTimelong예콜백 시간콜백 알림 시간
orderCreateTimelong예주문 생성 시간
orderIdString예주문번호플랫폼 주문 번호(고유)
statusString예결제현황SUCCESS, FAIL
typeString예주문 유형PAYMENT로 고정
userAmountdecimal예사용자가 실제로 지불한 금액
userCurrencyString예사용자 통화
userReceivableAmountdecimal예이용자 채권금액
walletUserIdint64예월렛 내부 사용자 IDOpenAPI를 통해 이 주소로 내부 지갑 결제 또는 출금 시 반환
signString아니요서명값MD5 서명(자세한 내용은 서명 알고리즘 참조)

상태 상태 설명​

상태 값설명
SUCCESS완료
FAIL실패

콜백 응답 요구사항​

판매자가 콜백을 성공적으로 처리한 후에는 다음 콘텐츠가 반환되어야 합니다.

success

시스템이 success 문자열을 수신하면 콜백 처리가 성공한 것으로 간주되어 다시 전송되지 않습니다.

콜백 재시도 메커니즘​

만약:

  • 응답을 받지 못했습니다.
  • 반환된 콘텐츠는 success가 아닙니다.
  • HTTP 요청 예외
  • 서비스 시간 초과

시스템은 콜백 알림 전송을 자동으로 다시 시도합니다.

최대 재시도 횟수​

14次

재시도 간격​

15s
15s
30s
180s
600s
1200s
1800s
1800s
1800s
3600s
10800s
10800s
21600s
21600s

반복적인 콜백으로 인한 비즈니스 데이터의 반복 처리를 피하기 위해 판매자 시스템에서는 orderId에 따라 멱등성 처리를 구현하는 것이 좋습니다.

서명 확인

콜백 알림을 받은 가맹점은 먼저 서명 검증을 수행한 후 검증을 통과한 후 비즈니스 로직을 실행해야 합니다. 서명 알고리즘은 주문 요청 서명 규칙과 완전히 일치합니다. "2. 서명방법"을 참고하시기 바랍니다.

서명 확인 절차​

  1. 콜백 매개변수에서 sign를 가져옵니다.
  2. 매개변수에서 sign를 제거합니다.
  3. 매개변수에 판매자 key를 입력하세요.
  4. 판매자 secret를 사용하여 서명 규칙에 따라 서명을 다시 계산합니다.
  5. 계산 결과가 콜백의 sign와 일치하는지 비교

서명 확인이 성공한 후에야 주문 업무가 진행됩니다.

Java 서명 확인 예시​

public void notify(JSONObject data) {

    log.info("收到回调通知：{}", data.toJSONString());

    String key = "your_key";
    String secret = "your_secret";

    String sign = data.getString("sign");

    data.put("key", key);
    data.remove("sign");

    String calculatedSign = SignUtils.getSign(data, secret);

    if (!calculatedSign.equals(sign)) {
        throw new DxBizException("签名验证失败");
    }
    // 业务处理逻辑
}